File Importer:
map.w3x lookuppaths ( directory | { diskfilepath archivefilename } )
The Grimoire Extension Pack, or short Grimex, is a set of tools that integrates nicely into Grimoire/Jass NewGen. These tools can also be used standalone by calling them from the command line, batch scripts or custom programs. Included in this documentation are also a bunch of core Grimoire hacks, that many people might not know about.
This section contains a list of expected parameters for each tool that is part of the Grim Extension pack. People who are using the tools from command line will need these parameters. Also the arguments for a vJASS external call can be derived from these usage instructions. So whoever is familiar with command line will probably find this section enough to get started.
File Importer:
map.w3x lookuppaths ( directory | { diskfilepath archivefilename } )
Path Mapper:
map.w3x lookuppaths (checkflags | checktiles) applyflags [checkmode] [applymode]
Tile Setter:
map.w3x lookuppaths tileset tilelist
File Exporter:
map.w3x lookuppaths [targetdir]
Object Merger:
map.w3x lookuppaths [ m | r | i ] mergefile { moremergefiles }
map.w3x lookuppaths ( w3u | w3t | w3b | w3d | w3a | w3h | w3q ) originalid newid { changeid [ level | variation ] value }
Constant Merger:
map.w3x lookuppaths mergefile { moremergefiles }
Trigger Merger:
map.w3x lookuppaths { war3map.wtg | war3map.wct }
Patch Generator:
script.lua lookuppaths patchname { flags }
For all tools the first argument is the path of the map being modified and the second parameter is a list of lookup directories that is used to resolve relative paths of other files passed in. You can pass "" if you're not using relative paths. Otherwise this is a string of all the paths separated by a ; and with \ replaced by /. If any of the paths contains a space then simply put the whole list in brackets. For example the lookup paths could be "C:/MyMap/;./jass/".
Remember that all this is beta software, there may still be bugs. In case something goes wrong, simply make use of JassHelper's backups and report bugs at the forums at www.wc3campaigns.net!
Since the version 1.0 of Grim Extensions all included tools can now be controlled with lua-scripts as well. This makes them even more powerful, flexible and usually a lot faster. To make use of this feature, instead of the usual parameters you have to pass one or more lua files (with the extension .lua) to the tool:
All Tools:
map.w3x lookuppaths script.lua { more.lua }
Check out the LUA scripts in the grimext/samples/ folder to find out how the scripting language works and which functions are available.
The File Importer plugin enables you to import a list of files or simply a folder including all subdirectories into your map. It can also auto-convert images to BLP format and MDL files to MDX due to its integration of BLPaletter and MDLXConverter. Additionally it will add appropriate icon borders and resize icons based on a naming convention.
When working on a map it is useful to keep all imports that are still being worked on in a folder that gets auto-imported by the File Importer tool as soon as the map is saved. That way the map always contains an up-to-date version of all your custom files. While working on a model or texture you can test your work ingame within seconds, without the hassle of having to convert and import the files manually. When distributing a system that requires imported files, an external call to the File Importer in the system's script will make sure that the required files are properly imported. An example would be the Dummy.mdx model from the caster system.
There are two ways to use the File Importer. From the menu you can click Extensions/Import Directory and select the directory that you want to import or you add a vJASS external call to your JASS script. The selected directory will then be imported into the map including the directory structure of all subdirectories. The imported files wil generally use the same path that they have inside the imported folder. The second option is using a vJASS external call, here's an example that will import the contents of C:\MyMap:
These external calls are evaluated whenever the map is saved, so the up-to-date files from that directory will always replace older imported files in the map. Relative paths to the map's directory and the lookup paths defined under [lookupfolders] in mapcompiler.conf (the JassHelper configuration file) are automatically resolved:
vJASS:
//! external FileImporter ..\MyMap
If you don't want to import a whole directory, but only a few files, then you can use Extensions\Import Files from the menu and select the files you want to import. When using an external call to import specific files you'll have to specify a list of pairs of source file and target file names. The target file name is the name that it should have inside the map:
Note how you only need to change the file extension of the imported path to make use of the auto-convert function:
vJASS:When importing a whole directory, auto-convert will attempt to convert all files with a .jpg, .bmp, .tga or .mdl extension. If the conversion is successful the resulting file will be imported using the same path with only the extension changed to .blp or .mdx. Otherwise the original file is imported using its original path. You can explicitely overrule this attempt by keeping the same extension in the imported path, although it doesn't make much sense:
vJASS:
//! external FileImporter ..\MyMap\DiscoStu.mdl Models\DiscoStu.mdl
Finally there's a naming convention that will add icon borders to images with a certain prefix in the filename.
The icons in the following example will get a normal/autocast/passive icon border:
vJASS:
//! external FileImporter CMDBTNMyIcon.bmp MyIcon.blp AUTBTNOtherIcon.tga OtherIcon.blp PASBTNNewIcon.jpg NewIcon.blp
The imported path for icons doesn't matter, they will end up in ReplaceableTextures\CommandButtons\BTNMyIcon.blp, ReplaceableTextures\AutocastButtons\BTNOtherIcon.blp and ReplaceableTextures\PassiveButtons\BTNNewIcon.blp and a disabled version will automatically be put in ReplaceableTextures\CommandButtonsDisabled\DISIconName.blp. Now let's combine the prefixes to make use of a shared disabled icon:
vJASS:
//! external FileImporter AUTPASCMDSharedIcon.tga SharedIcon.blp
This will create a normal, a passive and an autocast version of the same icon and put the shared disabled version in ReplaceableTextures\CommandButtonsDisabled\DISSharedIcon.blp. Finally we can put attack/armor type borders and caster upgrade borders around our icons:
vJASS:
//! external FileImporter ..\MyMap\infocard-chaos-damage.tga InterfaceTextures\infocard-chaos-damage.blp ..\MyMap\level-infocard-undead-caster.tga InterfaceTextures\level-infocard-undead-caster.blp
As you can see, the infocard- and level-infocard- prefixes do the magic here. Since infocard icons do not have disabled versions, the imported path will not be changed in this case. If an icon doesn't have the appropriate size, it will be resized automatically by the tool. If you use a custom icon style in your map or mod, you can customize the borders and overlays used by the tool. You'll find them as TGA files inside the directory where the Extensions are installed to. Also remember that the tool will never try to modify BLP files, the auto-bordering and resizing is only applied to BMP, TGA and JPG images.
If you want the imported files to show up in the import manager you need to close and reopen the map WITHOUT manually saving it. When using the tool from the menu this step is MANDATORY.
You can specify a callback function which provides the compression details for each auto-converted image. And of course you can speed up single file imports a lot, because this is now just one external call.
The Path Mapper plugin enables you to post-process the pathing map of your map after saving it. It's good for changing the walkability/flyability/buildability of specific tiles or of terrain cells that meet some other certain creteria. This allows for a number of tricks like making cliffs walkable or for example in Project Revolution we used it in combination with the 'Placement Prevented By' field to make refineries only buildable on geysirs.
The following example makes the map unwalkable where Lordaeron Summer Dirt, Lordaeron Summer Grass or Lordaeron Summer Dark Grass is:
Here is another example that sets the pathing to normal ground where tiles other than Lordaeron Summer Dirt are:
To be able to use it you'll need a bit more information. First of all you'll need to know the tile ids, which you can obtain from TerrainArt\Terrain.slk or from this list. Then you'll need the pathability flag table to determine which values you want to apply to the pathing map.
The flag values here are hexadecimal and need to be added up to combine the flags, the mask argument for the tool also needs to be hexadecimal. Internally the pathing map is stored in a grid of 32x32 cells. That means that the smallest unit in the editor, a 128x128 cell is split up into 16 pathing cells, each of which is assigned a value from the above flag table. With this tool you're able to change this value for each of the cells. Here are some examples that you will typically find in a pathing map.
Now to modify the pathing map, you'll need a way to specify which cells will be changed and a way to apply flag values to the existing value of each cell. For the latter there are four different apply modes that you can use.
So in the first example only the no-walk-bit is set with a binary or and nothing else is changed. If you don't specify an apply mode, the old values are completely replaced by the value you specify. Like in the second example where it's set to normal ground. Check modes here can be either match or mismatch.
In the first example ! is used to change the pathing for all tiles that are not Lordaeron Summer Dirt. If you don't set this parameter the normal mode will apply the change for all specified tiles.
Instead of the tile of each cell you can also compare the current pathability value to decide which cell needs to be updated. When comparing to a pathability mask, the following compare modes can be specified.
Apply modes in this case are again |, &, and ^. In the next example map boundaries are made walkable by removing the no-walk-bit with a binary and:
In this next example areas that have either the no-walk or the no-fly bit set, are made walkable and flyable:
If you ever decide to add walkability to a tile that is normally unwalkable, please note that this will update ALL cells that have this tile. That means that units will also be able to walk over cliffs, doodads and possibly water and the camera bounds when those are covered with the specified tile. In such cases can use the pathing configuration that is part of UMSWE instead of this tool.
You can specify callback functions for the condition that a cell needs to meet to be updated and for the update action, making it a lot more flexible and faster. Also the tool becomes a lot more user friendly, because you can save yourself the hassle of bitwise flag operations.
The Tile Setter plugin allows you to edit the tileset of your maps similar to the already existing option in the world editor. The only major difference is that this tool extends the tile limit to 16. This will make the old tileset editor of WEU obsolete. You can also change the base tileset with this tool, in case you want to switch to a different water/cliff look.
Using it is quite simple, just click Extensions\Edit Tileset from the menu, then a graphical tile picker will pop up. At the bottom it shows the base tileset of your map and a list tiles currently present in your map like so:
By clicking on the tile icons you can add/remove it to/from your map. The max is 16 tiles for each map. When you're satisfied with your changes click the ok button to apply them, then close and reopen your map without resaving it, and your new tiles should show up in the terrain palette.
The configuration dialog might spit out a warning if you removed or replaced cliff tiles with non-cliff tiles. This can only cause problems if the removed/replaced tile has actually been used for cliffs in your map, otherwise it's safe to ignore the warning.
You shouldn't ever need to use the Tile Setter from a vJASS external call, but in case you can think of any situation where this could be useful, here's an example that changes the terrain of your map into the Lordaeron Summer tileset. Use this tileset list and this this list of tiles as a reference for your calls:
vJASS:
//! external TileSetter L LdrtLdroLdrgLrokLgrsLgrd
Do NOT replace cliff tiles that are actually used as cliffs in your map. Please remove those cliffs from your terrain before exchanging the tile to prevent possible problems, unless you know what you're doing.
You can edit your tile list programmatically and use several functions to query details about each tile.
The File Exporter plugin simply exports all files inside a map to a specified folder. It will also rebuild the folder structure from inside the map in the specified target directory. That way the target directory can the again be used as the source directory for the File Importer plugin. This can be useful to copy the files from a system that is distributed through a demo map to your own map. For example one could export all contents of the Ultimate Terraining Map and import them all into a custom map using the File Importer and Object Merger plugins with just a few clicks. Or it can be used to copy the terrain, units, doodads, sounds, regions, or cameras from one map to another map.
To get all files extracted simply click Extensions\Export Files in the menu and select the target directory. This will essentially extract all files listed in the import manager, but also some internal files that contain special data. For each category of files the tool creates a separate subdirectory in the target directory, here's the list:
On a final note, all files that are used as input for the Object Merger, Trigger Merger or Constant Merger plugins should have been exported using this File Exporter plugin or by the export function of the WE before. That is because it takes care of inlinig TRIGSTR references when exporting the files, which prevents strings from getting lost when importing those files into other maps. If the files however had been exported using a normal MPQ viewer, the strings will not be inlined properly and may get lost. Also if you ever want to use the File Exporter in a vJASS external call, here's an example that exports all files to C:\MyMap:
vJASS:
//! external FileExporter C:\MyMap
None so far.
You can also export single files to specific directories.
There are two basic use cases for the Object Merger plugin. First of all it can import object editor data, but it won't replace the existing data, instead it will merge the existing and the imported data, there are different modes available that control how collisions of object ids are handled. This can be useful for distributing systems that require certain objects, like for example the caster unit from the caster system. A vJASS external call to this tool will make sure that the required unit exists in the map. Also in a team people can work separately on certain aspects of the map and later merge their work this way. The other use case is generating larger amounts of similar objects using vJASS external calls. Again this is useful to distribute systems that require object data. I'm thinking of systems like Bonus Mod which requires a number of bonus abilites. Finally it allows you to specify custom rawcodes for your objects, although this is conveniently possible with a Grimoire hack already.
When merging or generating object data, the first thing you'll have to know is what type of objects each file extension is associated with. Here's the list:
To merge object data there are three different modes available how collisions can be handled. Each of them is available from the menu as well as from vJASS external calls.
When using one of the menu entries a popup wil ask you to select all input files that you want to add to the map. All the input files need to be of the sime type of course, you cannot mix unit and ability definitions for example. Our first example shows how to import custom unit data that was previously exported by the File Exporter plugin using a vJASS external call:
The above is the same as the following call that explicitely defines how collisions should be handled, because m is the default mode:
vJASS:
//! external ObjectMerger m Objects\war3map.w3u
It's important that the merged files have been exported with the WE's export function or the File Exporter tool and not using an MPQ viewer, because otherwise string references may get lost. The second example shows how to import several files of the same type (extension) with one call. In case of collisions the existing object will be completely replaced (r parameter):
Ok, with this tool you can also create new objects using a vJASS external call instead of the object editor. I'll start with a few examples and then explain the parameters. This one creates a copy of the glaive upgrade with 2 levels and a different icon on the second level:
vJASS:Here's one that creates a new armor bonus ability that gives a bonus of 64 at level 1, the second call then creates a new item based on the existing protective ring item. It is assigned the new ability and a new name:
vJASS:This next example makes a copy of the fence doodad (NOfl), changes it so it has three variations and then tints the first variation all blue, the second variation all green and the third variation red:
vJASS:This last example creates a chaos ability to morph into a peasant. Apparently Warcraft doesn't mind abilities having the same id as units, so I gave the ability hpea as id:
Now let's use the last example to take a closer look at the parameters. First of all you'll need to specify the type of object that you want to create. This is done by putting the file extension of this type as the first parameter, use this table as a reference. The example has w3a which means we're creating an ability. The next parameter is the rawcode of the base object that we want to copy, this can be a standard object or also a custom object that you previously created in the object editor or with a previous call to this Object Merger tool. To find out the rawcode of an object use View/Display Values as Raw Data from the object editor menu. The third parameter is the id that the created object should have, you're free to choose any 4-letter-id that isn't already used by an object of the same type. Then follows a list of pairs or triples that specifies the changes you want to apply to the base object. The first pair here is anam "My Chaos" which sets the name of the created ability to My Chaos. The left part of such pairs is a 4-letter-change-id that determines which field should be updated, the right side is the new value. The next one sets the editor suffix, as you can see the quotes are not needed if the string doesn't contain spaces. Then the check tech dependencies flag is set to false. You'll notice that booleans are simply represented by 1 (true) and 0 (false). Finally there's also an example for a change triple. This is needed for fields that can be changed per level. In this case the target unit id for the chaos morph is set to hpea for level 1. If you're not sure if a field requires a pair or a triple, you can test it by increasing the level of the base ability in the object editor and looking if the field repeats for multiple levels. Upgrades also use levels for some fields as you can see in the first example where the icon is changed for level 2 of the upgrade. Doodad variations work similar. In the third example such triples are used to change the tinting values of the 3 variations of the created doodad. All other object types like units, items, buffs and destructables only use pairs and never triples because they don't have levels.
At this point you may wonder where to look up all those change ids. The answer is that with Grimoires object editor hack the ids of each change will be shown in brackets. Make sure that View\Display Values as Raw Data is disabled when you want to view these ids. Alternatively you can look up the ids in the appropriate MetaData.slk file for the respective object type. On a note about the inner workings, all vJASS external calls get evaluated whenever the map is saved. That means whenever you save the Object Merger will create the same objects that will overwrite each other over and over again, which isn't necessary, so after the first time you save you can technically remove the external call again.
Be careful when choosing the ids of your generated objects. Don't use ids that already exist, this can overwrite your existing objects. If you want the new objects to show up in the object editor you need to close and reopen the map WITHOUT manually saving it. When using the tool from the menu this step is MANDATORY. Also do only merge object files that have been exported with the File Exporter tool to Objects\ or the export object data function of the world editor. Otherwise TRIGSTR references could be missing.
First of all you can speed it up a lot, because you can create all your objects in a single external call. Then there are some additional functions available which you can use to reset objects, reset changes and apply changes to specific objects, all custom, all original, all modified original, or all unmodified original objects with a single script call. Also you can use LUA to program custom formulas to generate your object ids and for autofill-like needs.
The Constant Merger plugin works quite similar to the Object Merger tool, but instead of object editor data it imports customizations to the gameplay constants, the game interface settings and certain test map settings. If one of your system requires a specific change to the game interface or gameplay constants you can use a vJASS external call to this tool so that the required changes are automatically applied to a map that uses your system when it is saved. For example you might want to change the chat recipient prefixes for a chat system or you might want to customize the experience gain table for a levelup system.
Usually you will want to import customizations that were exported previously from another map by using the File Exporter tool. All files that it places inside the Constants\ folder after the export can be handled by the Constant Merger. There are three types of files that can be handled:
You can merge several files of the same type with a single Constant Merger call, but do NOT mix different types in a single call. This tool is also available from the menu Extensions\Merge Constants Data which pops up a file selection dialog. The other option is a vJASS external call like in this example:
vJASS:
//! external ConstantMerger C:\MyMap\Constants\war3mapSkin.txt ..\otherInterfaceStuff.txt
If you want your changes to show up in the editor you need to close and reopen the map WITHOUT manually saving it. When using the tool from the menu this step is MANDATORY. Also do only merge files that have been exported with the File Exporter tool to the Constants\ folder. Otherwise TRIGSTR references could be missing.
It's also possible to set values from within the LUA script, not only by merging files.
The Trigger Merger plugin is capable of adding the trigger data form another map to your map. That means it can import variables, GUI triggers and also the custom text triggers and header. So technically it is now possible to distribute GUI trigger systems that are easy to import into any map.
Use it with caution though, since variables and triggers that have the same name like existing variables/triggers will overwrite them. So if you're developing a system that you want to distribute this way you'd better use a unique prefix for your variables and triggers to prevent possible conflicts. Also the custom text header of the imported trigger data will be put into a new custom text trigger, so that the existing custom text header of your map won't be touched. The input for the tool is pair of wtg and wct files. You only need to specify one of the two as the input file, the tool will look for a file with the same path and name and only the extension changed and use it as the second input file. The easiest way to obtain a wtg and wct file is by using the File Exporter tool which will put the trigger data into the Triggers\ subfolder of the export target folder. Trigger files that have been exported using a MPQ viewer shouldn't be used as input files, because they will be missing TRIGSTR references.
Again it's possible to use it from the menu using Extensions\Merge Trigger Data and then selecting one of the two input files in the file browser, or from a vJASS external call. Here's an example that will add the triggers from an external file to your map:
vJASS:
//! external TriggerMerger C:\MyMap\Triggers\war3map.wtg
You can also merge the trigger data of several maps with a single call, simply list all the files that you want to merge as parameters of the external call. However you should always only list one file of a wtg/wct pair, never both in the same call:
vJASS:
//! external TriggerMerger C:\MyMap\Triggers\war3map.wtg C:\OtherMap\Triggers\war3map.wct
If you want the imported triggers to show up in the editor you need to close and reopen the map WITHOUT manually saving it. When using the tool from the menu this step is MANDATORY. Also do only merge files that have been exported with the File Exporter tool to the Triggers\ folder. Otherwise TRIGSTR references will be missing. The tool also doesn't check for duplicate JASS functions, so if two imported custom text headers both contain the H2I function this will of course cause compile errors and needs to be manually fixed. Also if the imported data contains references to generated unit, destructable, item, sound, region or camera variables those will be lost in the target map.
You can register global GUI variables from within the script without having to merge files.
The Patch Generator has been created to produce World Editor patches, specifically to port UMSWE to NewGen. UMSWE has been implemented entirely in LUA scripts which are interpreted by this Patch Generator tool. This means you can use the Patch Generator to produce your own MPQ patches for the World Editor or the Warcraft 3 game. Check out the LUA scripts in the umswe\ subfolder of your NewGen directory for sample scripts. Here's how you call the tool from the command line:
Patch Generator:
script.lua lookuppaths patchname { flags }
The first parameter is the script you want to run, the second as usual is a list of directories used to lookup file paths that cannot be resolved. The third parameter is the name of your patch, a txt file with this name is created in the logs/ subfolder of NewGen when you run this tool. Then you can pass a list of options which will be registered as global boolean variables in the LUA space. This is useful so you can use the same LUA script to turn a patch on and off with only the passed option changed. For example you could pass in "enable=1" or "enable=0" and in the script you can use if enable then to act depending on that option. Again, the UMSWE scripts are good samples to learn from.
Via Extensions\Enable Local Files you can enable and disable local files on your system. When it's on Warcraft will load files from local folders with a higher priority than the files from the mpqs. This enables you to override war3patch.mpq with your own files, without messing with the mpq for rapid testing purposes. Local files means that inside your Warcraft directory you could place a Units\ subfolder and for example put a custom AbilityMetaData.slk file in there that will be loaded instead of the file from the mpqs. This way it's also possible to override files that normally don't load when imported into a map (like all the meta data files or CliffTypes.slk).
Using Extensions\Register Shell Extensions you can add items to the context menu of Warcraft maps and campaigns. When this is enabled and you right click a map or campaign the context menu that pops up will show a Play Fullscreen and Play Windowed option:
This is an improved version of the old No Limits patch that is integrated in Grimoire that removes unit, item, doodad and map size limits. With the menu entry Grimoire\Disable WE Limits you can enable and disable this feature.
Additionally the possibility to create epic 480 x 480 maps has been added to the editor. But watch out, some people have told me about blight not working properly in maps that large. As you can see the hack is directly integrated into the create map dialog:
The menu entry Grimoire\Customize Test Map Settings will show the following configuration dialog:
As you can see it allows to speed up the game speed for your tests (just like you normally speed up replays) by a factor of up to 25. It can also disable fog of war and the victory and defeat conditions for your test runs in case you are testing a melee map. Additionally you can play around with player colors, add computer controlled players for your tests and assign custom handicaps and even ai scripts.
However make sure that Use Custom Forces is disabled in the force properties of your map, otherwise the test map settings will not work. With the upper left checkbox you can also enable and disable the custom test map settings. When it's disable the map starts as usual when clicking the test map button, otherwise the custom settings will be applied.
Finally there's a new hack that allows you to specify custom rawcodes for new objects in the object editor. It can be enabled and disabled with the Grimoire\Enable Object Editor Hack menu entry. Additionally all object properties will also show their internal rawcode in brackets. You will need those if you want to use the Object Merger tool in your map. Here's a screenshot of the hack in action:
By the way this hack can be used to create copies of non-hero units and even buildings which are heros. This is done by simply capitalizing the first character of the new unit id.
Here I'd like to thank everyone who has contributed in the creation and testing of the Grim Extension Pack and the Jass NewGen Pack as a whole. Special thanks go to the following people:
Have fun, PitzerMike